home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.n / grab.n < prev    next >
Text File  |  1995-07-25  |  8KB  |  199 lines
  1.  
  2.  
  3.  
  4.      ggggrrrraaaabbbb((((nnnn))))                      TTTTkkkk (((( ))))                       ggggrrrraaaabbbb((((nnnn))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           grab - Confine pointer and keyboard events to a window  sub-
  12.           tree
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ggggrrrraaaabbbb ?----gggglllloooobbbbaaaallll? _w_i_n_d_o_w
  16.           ggggrrrraaaabbbb _o_p_t_i_o_n ?arg arg ...?                                     |
  17.      _________________________________________________________________
  18.  
  19.  
  20.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.           This command implements simple pointer  and  keyboard  grabs
  22.           for  Tk.   Tk's grabs are different than the grabs described
  23.           in the Xlib  documentation.   When  a  grab  is  set  for  a
  24.           particular  window,  Tk  restricts all pointer events to the
  25.           grab window and its descendants in  Tk's  window  hierarchy.
  26.           Whenever  the  pointer  is within the grab window's subtree,
  27.           the pointer will behave exactly the same  as  if  there  had
  28.           been  no  grab at all and all events will be reported in the
  29.           normal fashion.  When the pointer is outside _w_i_n_d_o_w's  tree,
  30.           button  presses  and  releases  and  mouse motion events are
  31.           reported to _w_i_n_d_o_w, and window entry and window exit  events
  32.           are ignored.  The grab subtree ``owns'' the pointer: windows
  33.           outside the grab subtree will be visible on the  screen  but
  34.           they  will  be  insensitive until the grab is released.  The
  35.           tree of windows underneath the grab window can include  top-
  36.           level  windows, in which case all of those top-level windows
  37.           and their descendants will continue to receive mouse  events
  38.           during the grab.
  39.  
  40.           Two forms of grabs are possible:  local and global.  A local
  41.           grab  affects only the grabbing application:  events will be
  42.           reported to other applications as  if  the  grab  had  never
  43.           occurred.   Grabs are local by default.  A global grab locks
  44.           out all applications on the screen, so that only  the  given
  45.           subtree  of  the  grabbing  application will be sensitive to
  46.           pointer events (mouse button presses, mouse button releases,
  47.           pointer  motions, window entries, and window exits).  During
  48.           global grabs the window manager  will  not  receive  pointer
  49.           events either.
  50.  
  51.           During local grabs, keyboard events  (key  presses  and  key
  52.           releases)  are  delivered  as  usual:   the  window  manager
  53.           controls which application receives keyboard events, and  if
  54.           they are sent to any window in the grabbing application then
  55.           they are redirected to the focus window.   During  a  global
  56.           grab  Tk  grabs the keyboard so that all keyboard events are
  57.           always sent to the grabbing application.  The ffffooooccccuuuussss  command
  58.           is  still  used to determine which window in the application
  59.           receives the keyboard events.  The keyboard grab is released
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/23/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      ggggrrrraaaabbbb((((nnnn))))                      TTTTkkkk (((( ))))                       ggggrrrraaaabbbb((((nnnn))))
  71.  
  72.  
  73.  
  74.           when the grab is released.
  75.  
  76.           Grabs apply to particular displays.  If an  application  has
  77.           windows  on  multiple  displays  then  it  can  establish  a
  78.           separate grab on each display.  The  grab  on  a  particular
  79.           display  affects  only  the  windows on that display.  It is
  80.           possible for different applications on a single  display  to
  81.           have  simultaneous local grabs, but only one application can
  82.           have a global grab on a given display at once.
  83.  
  84.           The ggggrrrraaaabbbb command can take any of the following forms:
  85.  
  86.           ggggrrrraaaabbbb ?----gggglllloooobbbbaaaallll? _w_i_n_d_o_w
  87.                Same as ggggrrrraaaabbbb sssseeeetttt, described below.                       |
  88.  
  89.           ggggrrrraaaabbbb ccccuuuurrrrrrrreeeennnntttt ?_w_i_n_d_o_w?                                              ||
  90.                If _w_i_n_d_o_w is specified, returns the name of the current  |
  91.                grab window in this application for  _w_i_n_d_o_w's  display,  |
  92.                or  an  empty  string  if  there is no such window.  If  |
  93.                _w_i_n_d_o_w is omitted, the command  returns  a  list  whose  |
  94.                elements  are  all  of  the  windows  grabbed  by  this  |
  95.                application for all displays, or an empty string if the  |
  96.                application has no grabs.                                |
  97.  
  98.           ggggrrrraaaabbbb rrrreeeelllleeeeaaaasssseeee _w_i_n_d_o_w                                                ||
  99.                Releases  the grab on _w_i_n_d_o_w if there is one, otherwise  |
  100.                does nothing.  Returns an empty string.                  |
  101.  
  102.           ggggrrrraaaabbbb sssseeeetttt ?----gggglllloooobbbbaaaallll? _w_i_n_d_o_w                                          ||
  103.                Sets  a  grab  on _w_i_n_d_o_w.  If ----gggglllloooobbbbaaaallll is specified then  |
  104.                the grab is global, otherwise it is local.  If  a  grab  |
  105.                was  already in effect for this application on _w_i_n_d_o_w's  |
  106.                display then it is automatically released.  If there is  |
  107.                already   a   grab  on  _w_i_n_d_o_w  and  it  has  the  same  |
  108.                global/local form  as  the  requested  grab,  then  the  |
  109.                command does nothing.  Returns an empty string.          |
  110.  
  111.           ggggrrrraaaabbbb ssssttttaaaattttuuuussss _w_i_n_d_o_w                                                 ||
  112.                Returns  nnnnoooonnnneeee  if  no  grab is currently set on _w_i_n_d_o_w,  |
  113.                llllooooccccaaaallll if a local grab is set on _w_i_n_d_o_w, and gggglllloooobbbbaaaallll if a  |
  114.                global grab is set.
  115.  
  116.  
  117.      BBBBUUUUGGGGSSSS
  118.           It took an incredibly complex and  gross  implementation  to
  119.           produce  the  simple grab effect described above.  Given the
  120.           current implementation, it isn't safe  for  applications  to
  121.           use  the  Xlib  grab facilities at all except through the Tk
  122.           grab procedures.  If applications try to manipulate X's grab
  123.           mechanisms directly, things will probably break.
  124.  
  125.           If  a  single  process  is  managing  several  different  Tk  |
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/23/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      ggggrrrraaaabbbb((((nnnn))))                      TTTTkkkk (((( ))))                       ggggrrrraaaabbbb((((nnnn))))
  137.  
  138.  
  139.  
  140.           applications,  only  one  of  those  applications can have a  |
  141.           local grab for a given display at any given  time.   If  the  |
  142.           applications  are  in  different processes, this restriction  |
  143.           doesn't exist.
  144.  
  145.  
  146.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  147.           grab, keyboard events, pointer events, window
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/23/95)
  196.  
  197.  
  198.  
  199.